# Tags Overview

**Category:** Features/Enrich/Tags

## Overview

### Introduction

This document provides an overview and usage guidelines for the Tags feature in Wix Patterns. Tags are labels that can be attached to entities, offering a flexible way to categorize and manage data.

### Feature Overview

Tags in Wix Patterns are supported in multiple areas. They are primarily used in two contexts:

- **Collection Page**: Where tags can be used to organize and filter entities in a table view.
- **Entity Page**: Where tags can be managed for individual entities through the TagsWidget.

Tags Limit: Users can create up to 100 tags per entity and accordingly assign up to 100 tags to a single item.

#### Using Tags in the Collection Page

You can opt-in to the Tags feature on collection page by using the `tags` prop in the `Table` component. The `tags` prop accepts a `Tags` component that you should import from `@wix/patterns`. The following features are supported:

- Displaying tags as a column in the entities table
- Filtering the table by tags
- Bulk assigning tags to multiple entities
- Adding, updating, and deleting tags via modal

##### Supported Components

The Tags feature is supported in the following components:

- Table
- TableGridSwitch (only the table view)
- TableFolders
- TableGridSwitchFolders (only the table view)

#### Using Tags in the Entity Page

Using tags in entity page can be used to manage tags for a specific entity. The following features are supported:

- Viewing all tags associated with the entity
- Assigning new tags to the entity
- Removing existing tags from the entity

Read more about [Tags](./?path=/story/features-enrich-tags--tagswidget).


## Server Prerequisites


### Overview

The backend implementation of tags can be divided into two parts:
1. **Management of which tags exist for each FQDN** - This is handled by the [Tags Service](https://github.com/wix-private/wixos/tree/master/tags-service), which is managed by Wix Patterns. This service is responsible for creating, updating, and deleting tags for each FQDN.

2. **Management of which tags are assigned to each entity** - For implementation details, please refer to the official guidelines provided by P13n [here](https://github.com/wix-private/server-infra/tree/master/framework/loom-prime/examples/prime-tags). Currently, the endpoint with filter functionality is not supported on the client side. If you require this functionality, please contact us directly.

### Adding support for tags for specific entity

#### Tags Field
The entity should have a `tags` field in the entity's schema. It should be of type as described in this [protobuf](https://github.com/wix-private/p13n/blob/186e5c8cc7245686cc8f5558672d34f9075ef7a2/protos/common/src/main/proto/wix/common/tags.proto#L33). On Scala, you can import it from `wix.common.tags`. For example, a product entity can be defined in the following structure:

```js
{
  id: "123",
  name: "Super shoes",
  tags: {
    privateTags: {
      tagIds: ["222","333"]
    },
    tags: {
      tagIds: ["444","555"]
    }
  }
}
```

An example for defining the `tags` field in a proto file:

```js
message Product {
  option (.wix.api.entity) = {
    fqdn: "wix.ecom.catalog.v1.product"
    taggable: {}
    extensible: {}
  }
  string id = 1;
  string name = 2;
  wix.common.tags tags = 3;
}
```

**More details and limitations on tags:**
- Each entity can be labeled with multiple tags.
- Maximum of 100 tags per entity.
- Each tag is a short string (max 250 characters) and is case-insensitive.
- No enforcement on the character set.
- Tags must be unique on a given entity. Assigning a tag to an entity that already has it assigned is a no-op, with no error returned. The same applies when attempting to unassign a tag that the entity does not have.
- Currently, Wix Patterns supports only private tags. Public tags are not supported.
- Private tags are not presented to UoU and should be filtered out from any UoU responses.

#### Permissions and Security

- The permission on the `BulkUpdateTags` endpoint should be separate from the `update` endpoint to allow assignment to specific users/apps without granting full edit capabilities.
- The permission to assign/unassign private tags must be separate from the permission to write the entity itself. This is to prevent a user-of-user (UoU) with entity write permissions from labeling it (e.g., a UoU can create an order but must not be able to label it).
- This can be achieved by using [conditional fields](https://dev.wix.com/docs/rnd-general/articles/p13n-guidelines-aips/guidance-aips/design-patterns/7001-partial-responses-projections).

#### API Parameters
As demonstrated in the example above, the API should receive:
- List of entity IDs to update
- List of tag IDs to assign to all specified entities
- List of tag IDs to remove from all specified entities

#### Query Entity
When using private tags, ensure private tags are filtered out from the response to prevent visibility to UoU.